home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / bbs / tmg107.zip / EXTERNAL.DOC < prev    next >
Text File  |  1997-04-11  |  26KB  |  489 lines
  1.   EXTERNAL.DOC                                                       Page  1
  2.   ╒═════════════════════════════════════════════════════════════════════════╕
  3.   │             The Magic Gate version 1.07                                 │
  4.   │             Documentation  April '97                                    │
  5.   │             (C) Copyright 1995 - 1997 All Rights Reserved               │
  6.   │               Joseph O'Connor                                           │
  7.   ╘═════════════════════════════════════════════════════════════════════════╛
  8.  
  9.         This game may be distributed in its original, unmodified form as
  10.   long as no money is made off of it.  Please do not include the contents
  11.   of this archive in any CD, collection, or whatever without express written
  12.   permission of ME!
  13.  
  14.   This file was written for all you code-heads out there who are interested
  15.   in writing an external module for TMG.  This will document all the
  16.   structures for the various things in TMG as well as giving insight into how
  17.   to put new EXMODS into the game.  If you're a code-junkie like me, and want
  18.   to write your own thing for everything, then this is the file you need to
  19.   get started.
  20.  
  21.  
  22.   ─═════════════════════════════════════════════════════════════════════════─
  23.   Introduction:
  24.  
  25.   If the TMGSL is not powerful enough for you, or you need to do something
  26.   totally different in your EXMOD, you should have the ammunition you need
  27.   to get writing the code after reading this file.  You will learn the format
  28.   of the drop file as well as the method for adding your EXMOD to the
  29.   EXMODS.DAT file as well (which is just as useful for scripts).  Even if you
  30.   don't plan on writing an EXMOD, this file will contain some techie stuff
  31.   you might be interested in.
  32.  
  33.   EXTERNAL.DOC                                                      Page  2
  34.   ─═════════════════════════════════════════════════════════════════════════─
  35.   Constants in the game:
  36.  
  37.   Oh geez, there are about a million constants in this program.  Mainly
  38.   because its so much easier to remember CLASS_MAGE then it is to remember if
  39.   mages were 2 or 8.  Not all of these will apply 100% to each and every
  40.   EXMOD, but some of them will be vital to understanding the values of some
  41.   of the fields.
  42.   
  43.   Go figure, well, anyway, here is a list of constants that relate to file 
  44.   names.
  45.  
  46.   CHAR_FILE='PLAYERS.DAT';         This file has all the player data
  47.   GUILD_FILE='GUILDS.DAT';         This file has all the guilds data
  48.   STAT_FILE='MAGISTAT.DAT';        This contains the configuration for the
  49.                                    game, such things as costs etc.
  50.   MENU_TEXT_FILE='MAGITEXT.DAT';   This has all the menus and unchanging text
  51.   HOLD_FILE='HOLD.DAT';            This is used to tell any running copies not
  52.                                    to access the disk drive temporarily
  53.   WEAPON_FILE='WEAPONS.DAT';       This file contains data for all the weapons
  54.   ARMOR_FILE='ARMORS.DAT';         This file contains data for all the armors
  55.   SHIELD_FILE='SHIELDS.DAT';       This file contains data for all the shields
  56.  
  57.   GRANK_ANS_FILE='GRANK.ANS';      This file contains the ANSI guild ranks
  58.   GRANK_ASC_FILE='GRANK.ASC';      This file contains the ASCII guild ranks
  59.   PRANK_ANS_FILE='PRANK.ANS';      This file contains the ANSI player ranks
  60.   PRANK_ASC_FILE='PRANK.ASC';      This file contains the ASCII player ranks
  61.  
  62.   These constants should be used for any call to open, close, read whatever
  63.   it is you want to do to the file cause it will make your life a lot easier
  64.   if I ever decide to change a file name ;)
  65.   Alright, moving along, next we have all the possible flags that can affect
  66.   the character and are stored in the main_char^.char_flags long integer.
  67.   These determine the actions that the character has performed and determine
  68.   which cans can still be performed if the oppurtunity arises.
  69.   
  70.   FLAGS_SHAMED_MASTER=1;        This flag is set if the character attacks
  71.                                 another character with the same master.
  72.   FLAGS_MASTER_IGNORES=2;       This flag is set if the master will not do
  73.                                 anything for the character today.
  74.   FLAGS_EXPERT_MODE=4;          Are menus shown to the player?
  75.   FLAGS_LOUIS_THWARTED=8;       Louis has stopped the character from trying
  76.                                 to break into the inn.  All further attempts
  77.                                 are automatic failures that day.
  78.   FLAGS_FOUND_GATE=16;          Have they found the magic gate that day?
  79.   FLAGS_ENTERED_GATE=32;        Did they enter the gate that day?
  80.   FLAGS_HAS_BOW=64;             Does the character have a bow and arrow?
  81.   FLAGS_HUNTED=128;             Has a hit been put out on this character?
  82.   FLAGS_SEEN_SHADY=256;         Have they seen Shady today?
  83.   FLAGS_CHAR_DRUNK=512;         Did the character have one too many in the bar?
  84.   FLAGS_MET_TRAVELLER=1024;     Have they visited the Sage today?
  85.   FLAGS_DAILY_SECRET_1=2048;    Secret little things...
  86.   FLAGS_DAILY_SECRET_2=4096;    Secret little things...
  87.   FLAGS_DAILY_SECRET_3=8192;    Secret little things...
  88.   FLAGS_DAILY_SECRET_4=16384;   Secret little things...
  89.  
  90.   EXTERNAL.DOC                                                      Page  3
  91.   ─═════════════════════════════════════════════════════════════════════════─
  92.   Default values:
  93.  
  94.   The following are only used if there is no STAT_FILE.  They are the defaults
  95.   that will be written to the stat file.  They're just sort of here for you
  96.   to look at.
  97.  
  98.   DEFAULT_GRACE=15;             
  99.   DEFAULT_RESURRECT=2;
  100.   DEFAULT_FIGHTS=25;
  101.   DEFAULT_PFIGHTS=3;
  102.   DEFAULT_MTRANSFER=10000;
  103.   DEFAULT_NTRANSFER=3;
  104.   DEFAULT_ATRANSFER=TRUE;
  105.   DEFAULT_BANK_RATE=6.00;
  106.   DEFAULT_HEAL_COST=4;
  107.   DEFAULT_INN_COST=300;
  108.   DEFAULT_DEATH_LOSE_EXP=10;
  109.   DEFAULT_MOB_GOLD_MULT=1.20;
  110.   DEFAULT_MOB_EXP_MULT=0.85;
  111.   DEFAULT_MAX_GUILDS=5;
  112.  
  113.   ─═════════════════════════════════════════════════════════════════════════─
  114.   Deciphering the Class variable:
  115.  
  116.   The next group of constants show the bits that correspond to each of the
  117.   six classes as they are in the main_char^.class integer.  They are vital
  118.   to knowing what the characters capabilities are.
  119.  
  120.   CLASS_WARRIOR     =  1;
  121.   CLASS_MAGE        =  2;
  122.   CLASS_THIEF       =  4;
  123.   CLASS_HEALER      =  8;
  124.   CLASS_RANGER      =  16;  <--+-These two were reversed in previous versions.
  125.   CLASS_PALADIN     =  32;   <-+
  126.   
  127.   MASTERED_WARRIOR  =  64;
  128.   MASTERED_MAGE     =  128;
  129.   MASTERED_THIEF    =  256;
  130.   MASTERED_HEALER   =  512;
  131.   MASTERED_RANGER   =  1024;<--+-These two were reversed in previous versions.
  132.   MASTERED_PALADIN  =  2048; <-+
  133.  
  134.   EXTERNAL.DOC                                                      Page  4
  135.   ─═════════════════════════════════════════════════════════════════════════─
  136.   Limits in TMG:
  137.  
  138.   The following constants are used in my records to limit the number of chars
  139.   in the field, so I gave them all names that are easy to remember.
  140.  
  141.   SHORT_LENGTH=20;
  142.   MED_LENGTH=40;
  143.   MAX_LENGTH=86;
  144.   DESC_LENGTH=100;
  145.   
  146.   The next few constants are limits on the game as far as what would unbalance
  147.   it.  These numbers have been toyed and tinkered with from the start and they
  148.   are just about right for most any game now.
  149.  
  150.   MAX_WEAPONS=14;               Number of different ARMORS,WEAPONS and SHIELDS
  151.   MAX_LEVELS=20;                Total number of levels in the game.
  152.   MAX_DAMAGE_REDUCTION=87;      How little damage can you possibly deflect?
  153.   MAX_LUCK=30;                  Luck modifies quite a few things, and the
  154.                                 higher it goes, the easier it is to do well.
  155.   MOB_CATCH_CHANCE=20;          {MBL} Determines at what percentage a monster
  156.                                 will attack you when you try to flee from it.
  157.   BONUS_HIT_CHANCE=8;           {MBL} How often do you or the mob strike for
  158.                                 extra damage?
  159.   SKILL_GAIN_LEVEL=5;           The number of percentage points you gain when
  160.                                 you raise a level in your class.
  161.   SKILL_USAGE_NUM_LEVELS=5;     How many levels do you have to gain to earn
  162.                                 a special move usage point.
  163.   
  164.   {MBL} stands for "Modified by Luck" which means if you have a positive luck,
  165.         you will succeed at the task more frequently than average.  Conversly,
  166.         if you have a negative luck, you will succeed less frequently.
  167.  
  168.   The following denote the costs of various things that a character can pay
  169.   to have done in the game.
  170.   
  171.   BOW_COST=375;
  172.   KEY_COST=400; {This is 400*level*level (of the char w/ the higher level}
  173.   HIT_COST=1000; {this is 1000*level*level (of the char w/ the higher level}
  174.   STEAL_COST=500;
  175.   
  176.   
  177.   EXTERNAL.DOC                                                      Page  5
  178.   ─═════════════════════════════════════════════════════════════════════════─
  179.   Structures:
  180.  
  181.   Here, take a look at them, use them, you'll need to know them to write an
  182.   external program for TMG.  Anything in all caps is a constant you should
  183.   be able to find in the above section.  I've grouped the pointers together
  184.   with their associated record for easy viewing.
  185.  
  186.   ptchar=^chars;
  187.   chars=record
  188.     name:string[SHORT_LENGTH];          Characters Name
  189.     real_name:string[MED_LENGTH];       Players Name or Handle
  190.     virtual:integer;                    Their unique numerical value
  191.     class:integer;                      Tells what class/es the character has
  192.                                         mastered, and what is current.
  193.     sex:integer;                        1=Male 2=Female
  194.     attack:integer;                     The characters total attack value
  195.     defense:integer;                    The characters total defense value
  196.     damage_reduction:integer;           Total damage reduction.  Note, this
  197.                                         can go over MAX_DAMAGE_REDUCTION, but
  198.                                         the code will reduce it to max when it
  199.                                         figures out the damage.
  200.     charm:integer;                      The characters charm.
  201.     shame:integer;                      How shameful the character has been
  202.     luck:integer;                       How lucky the character is.
  203.     guild:integer;                      guild # the character belongs to 0=none
  204.     char_flags:longint;                 See the constants section for the XOR
  205.                                         values to use here.
  206.     hp:integer;                         The current hit points of the character
  207.     mhp:integer;                        The maximum hit points of the character
  208.  
  209.   The following are no longer referenced by TMG as of version 1.07
  210.   ─═════════════════════════════════════════════════════════════════════════─
  211.     weapon:integer;                     The number of points the characters
  212.                                         weapon adds to his attack value.
  213.     weapon_name:string[SHORT_LENGTH];   The name of the characters weapon.
  214.     armor:integer;                      The number of points the characters
  215.                                         armor adds to his defense value.
  216.     armor_name:string[SHORT_LENGTH];    The name of the characters armor.
  217.     shield:integer;                     The number of points the characters
  218.                                         shield adds to his damage reduction.
  219.     shield_name:string[SHORT_LENGTH];   The name of the characters shield.
  220.   ─═════════════════════════════════════════════════════════════════════════─
  221.  
  222.     gold:longint;                       Amount of gold carried
  223.     bankgold:longint;                   Amount of gold in the bank
  224.     gems:integer;                       Number of gems the character has
  225.     xfers_made:integer;                 How many bank transfers the char has
  226.                                         made that day.
  227.     experience:longint;                 How many experience points the char.
  228.                                         has accumulated towards levels.
  229.     level:integer;                      Characters current level.
  230.     skill_uses_max:integer;             Maximum # of special moves the char
  231.                                         can do in a day.
  232.     skill_uses_curr:integer;            The # of special moves the character
  233.                                         has left for the day.
  234.     skills:array[1..6] of integer;      The percentage values for each of the
  235.                                         six classes the character has.
  236.     1=Warrior 2=Mage 3=Thief 4=Healer 5=Ranger 6=Paladin
  237.   EXTERNAL.DOC                                                      Page  6
  238.   ─═════════════════════════════════════════════════════════════════════════─
  239.   Structures (cont.):
  240.  
  241.     location:string[SHORT_LENGTH];      String shown when someone uses the
  242.                                         (F)ind character command, for example
  243.                                         "sTonio's Armory"
  244.     time_entered:string[MED_LENGTH];    Don't even know if I've used this.
  245.     last_played:integer;                Last game day # the character played
  246.     died_on_day:integer;                Day # the character died on.
  247.     home_address:string[23];            Will be used in interbbs TMG someday
  248.     first_played:longint;               Time used for comparison between
  249.                                         characters as to who played first etc.
  250.     fights_left:integer;                # of creature fights left today.
  251.     player_fights_left:integer;         # of player fights left today.
  252.     dead:boolean;                       Is the character currently dead?
  253.     sleep_inn:boolean;                  Is the character sleeping in the inn?
  254.     sleep_guild:boolean;                Is the character sleeing in their
  255.                                         guild hall?
  256.     on_now:boolean;                     Is the character playing right now?
  257.     next:ptchar;                        used to link em all together...
  258.   end;
  259.  
  260.   EXTERNAL.DOC                                                      Page  7
  261.   ─═════════════════════════════════════════════════════════════════════════─
  262.   Structures (cont.):
  263.  
  264.   gamestat=record
  265.     on_day:integer;                     What Game day # are we on?
  266.     last_played:string;                 Used to determine whether maintenance
  267.                                         needs to be run or not.
  268.     date_started:string[MED_LENGTH];    Date the game was last reset.
  269.     grace_period:integer;               How long before a character is deleted
  270.                                         due to not playing.
  271.     resurrection_period:integer;        How long after a character dies that
  272.                                         he is automatically resurrected.
  273.     reg_code_1:longint;                 Registration Code #1
  274.     reg_code_2:longint;                 Registration Code #2
  275.     reg_code_3:longint;                 Registration Code #3
  276.     registered:boolean;                 Is it registered?
  277.     registered_to:string[MED_LENGTH];   Who is it registered to?
  278.     BBS_NAME:string[MED_LENGTH];        BBS Name being played on.
  279.     net_address:string[23];             BBS's network address for IBBS play...
  280.     net_mail_dir:string[MAX_LENGTH];    Directory where netmail is stored.
  281.     creature_fights_day:integer;        # of creature fights to give each day.
  282.     player_fights_day:integer;          # of player fights to give each day.
  283.     allow_transfers:boolean;            Allow money transfers via bank?
  284.     max_amount_transfer:longint;        How much can be transferred at most?
  285.     max_num_transfers:integer;          How many transfers to allow.
  286.     bank_rate:real;                     How much interest the character gets
  287.                                         on the gold they have in the bank
  288.     heal_cost:integer;                  How much it costs per level per hit 
  289.                                         point to have it healed.
  290.     inn_cost:integer;                   How much it costs per level to stay at
  291.                                         the inn.
  292.     death_lose_exp:integer;             Percentage of experience lost when you
  293.                                         die.
  294.     floating_gold:longint;              Amount of gold lost in the realms by
  295.                                         dying characters.
  296.     auto_calc:boolean;                  Auto-calculate mobs experience and gold
  297.                                         in the creature editor?
  298.     mob_gold_mult:real;                 Used with auto_calc as a multiplication
  299.                                         factor for gold.
  300.     mob_exp_mult:real;                  Used wiht auto_calc as a multiplication
  301.                                         factor for experience.
  302.     max_num_guilds:integer;             Maximum number of guilds to allow in
  303.                                         the game.
  304.     patch_level:integer;               Number of gems donated to the yet-to-
  305.                                         be-formed city council.
  306.   end;
  307.  
  308.   da_weapon=record                      These are the records used for
  309.                                         WEAPONS, ARMORS and SHIELDS.
  310.     name:string[short_length];          The items name
  311.     attack:integer;                     The amount this item adds to its
  312.                                         respective field.
  313.     cost:longint;                       How much does the item cost?
  314.   end;
  315.   weaps=array[1..MAX_WEAPONS] of da_weapon;
  316.   EXTERNAL.DOC                                                      Page  8
  317.   ─═════════════════════════════════════════════════════════════════════════─
  318.   Structures (cont.):
  319.  
  320.   The creature structure has changed as of version 1.06..
  321.   the old version follows.
  322.  
  323.   ptmob=^creature;
  324.   creature=record
  325.     name:string[MED_LENGTH];            The name of the creature.
  326.     level:integer;                      What level is the creature?
  327.     attack:integer;                     The attack value of the creature.
  328.     defense:integer;                    The defense value of the creature.
  329.     shield:integer;                     The damage resistance of the creature.
  330.     hp:integer;                         The max HP of the creature.
  331.     weapon_name:string[SHORT_LENGTH];   What weapon the creature uses.  This,
  332.                                         and armor_name really have no affect
  333.                                         whatsoever, just makes each monster
  334.                                         look that much more diversified.
  335.     armor_name:string[SHORT_LENGTH];    The creatures armor name.
  336.     death_line:string[MAX_LENGTH];      Displayed to character upon creature
  337.                                         being defeated (not implemented yet).
  338.     race:integer;                       This is what type of creature it is
  339.                                         and will determine its attributes.
  340.     gold:longint;                       Gold given to player who defeats it.
  341.     experience:longint;                 Exp given to player who defeats it.
  342.     verification_num:longint;           Number come up with through numerous
  343.                                         calculations so that monsters of each
  344.                                         level can be kept in the same range.
  345.     next:ptmob;
  346.   end;
  347.  
  348.   pt105mob=^creature;
  349.   creature105=record
  350.     name:string[MED_LENGTH];            The name of the creature.
  351.     level:integer;                      What level is the creature?
  352.     attack:integer;                     The attack value of the creature.
  353.     defense:integer;                    The defense value of the creature.
  354.     shield:integer;                     The damage resistance of the creature.
  355.     hp:integer;                         The max HP of the creature.
  356.     weapon_name:string[SHORT_LENGTH];   What weapon the creature uses.  This,
  357.                                         and armor_name really have no affect
  358.                                         whatsoever, just makes each monster
  359.                                         look that much more diversified.
  360.     armor_name:string[SHORT_LENGTH];    The creatures armor name.
  361.     death_line:string[MAX_LENGTH];      Displayed to character upon creature
  362.                                         being defeated (not implemented yet).
  363.     gold:longint;                       Gold given to player who defeats it.
  364.     experience:longint;                 Exp given to player who defeats it.
  365.     verification_num:longint;           Number come up with through numerous
  366.                                         calculations so that monsters of each
  367.                                         level can be kept in the same range.
  368.     next:pt105mob;
  369.   end;
  370.  
  371.   EXTERNAL.DOC                                                      Page  9
  372.   ─═════════════════════════════════════════════════════════════════════════─
  373.   Structures (cont.):
  374.  
  375.   ptrace=^race;
  376.   race=record
  377.     virtual:integer;
  378.     name:string[SHORT_LENGTH];
  379.     size:integer;
  380.     next:ptrace;
  381.   end;
  382.  
  383.   ptdesc=^desc;
  384.   desc=record
  385.     line:string[DESC_LENGTH];
  386.     next:ptdesc;
  387.   end;
  388.  
  389.   ptguild=^guild;
  390.   guild=record
  391.     virtual:integer;                    The guild number.
  392.     name:string[SHORT_LENGTH];          The guild name.
  393.     leader:integer;                     The virtual number of the guild leader.
  394.     hall:boolean;                       TRUE if they've built a hall.
  395.     password:string[SHORT_LENGTH];      Password to get into the guild.
  396.     credo:string[MAX_LENGTH];           Short description as to what the guild
  397.                                         is all about.
  398.                 The following are only used if hall is true.
  399.     gold_present:longint;               How much gold is present in the hall.
  400.     gems_present:integer;               How many gems are present in the hall.
  401.     guard_level:integer;                The level of the guild guardian.
  402.     guard_name:string[SHORT_LENGTH];    The name of the guild guardian.
  403.     guard_attack:integer;               The guard's attack value.
  404.     guard_defense:integer;              The guard's defense value.
  405.     guard_shield:integer;               The guard's damage resistance.
  406.     guard_hp:integer;                   The guard's hit points.
  407.     guard_weapon_name:string[SHORT_LENGTH];     (See mob weapon and armor name)
  408.     guard_armor_name:string[SHORT_LENGTH];
  409.     next:ptguild;
  410.   end;
  411.  
  412.   ptitem=^item;
  413.   item=record
  414.     name:string[SHORT_LENGTH];
  415.     attack:integer;
  416.     maxattack:integer;
  417.     cost:longint;
  418.     charges:integer;
  419.     wear_flags:integer;
  420.     required_level:integer;
  421.     flags:longint;
  422.     identified:boolean;
  423.     equipped:boolean;
  424.     scripts_used:longint;
  425.     scriptID:string[SHORT_LENGTH];
  426.     next:ptitem;
  427.   end;
  428.  
  429.   EXTERNAL.DOC                                                      Page 10
  430.   ─═════════════════════════════════════════════════════════════════════════─
  431.   Drop file:
  432.  
  433.   TMG creates a small drop file of its own that can be picked up and read by
  434.   an EXMOD.  The name of the file will be TMG<X>.DAT where <X> is the zero
  435.   padded node number.  The file name will always be 8 characters.
  436.   i.e. TMG00001.DAT would be the name of the drop file for node 1.  The file
  437.   format is pretty easy to follow, and doesn't necessarily change order, but
  438.   I may need to throw other things in there eventually so I have been using
  439.   keywords to tell what each line is for.  An example dropfile is below.
  440.  
  441.   NAME BASITEN                  This is the users character name.
  442.   UFNAME JOE                    This is the users first name.
  443.   ULNAME O'CONNOR               This is the users last name.
  444.   COMPORT 4                     This is the com port the EXMOD should use.
  445.   BAUDRATE 14400                This is the baud rate the modem is at. 
  446.   LOCKBAUD 0                    This is was baud rate the port is locked at.
  447.   ROUTINES INTERNAL             This is either INTERNAL or FOSSIL.
  448.   DROPFILEPATH C:\MAGIC\        This is the path to the BBS's drop file.
  449.   GRAPHICS 3                    3=ANSI, less is ASCII.
  450.   TIMELEFT 224                  This is how much time the user has left.
  451.  
  452.   This file is read back in when the user exits the EXMOD, and if your program
  453.   keeps track of time, it would be a good idea to write the drop file back
  454.   before your program ends.  The only thing that will be different is the
  455.   TIMELEFT statistic.
  456.   
  457.   EXTERNAL.DOC                                                      Page 11
  458.   ─═════════════════════════════════════════════════════════════════════════─
  459.   A Word about the EXMODS.DAT file:
  460.  
  461.   This file is how TMG knows that you have external modules installed into
  462.   your game.  It is a simple file consisting of three items (but not
  463.   necessarily only three lines).  Follow this format and have your EXMOD add
  464.   its own three items to the end of the file.
  465.  
  466.   <Command Line>
  467.   <Name of Module>
  468.   <Description>
  469.    ....
  470.   <Description>
  471.   ~
  472.   The command line is what is written to the batch file for execution.  It has
  473.   the special properties of being able to pass the node number as well with a
  474.   variable.  If you were to enter the command line as:
  475.   C:\MAGIC\EXMODS\HOUSE.EXE /n`*
  476.   and this was being called from node 2, the actual command executed would be
  477.   C:\MAGIC\EXMODS\HOUSE.EXE /n2
  478.   I may see a need to add other things like perhaps the path to the game or
  479.   some such thing, but for now `* is the only one.
  480.   The name of the module is simple.  It is the name users see when they go
  481.   to the Other Realms module.  This line can have color codes in it as well
  482.   to spiff it up.
  483.   The description is as many lines of text as you like to describe your module
  484.   but keep them as short as possible.  The users can take a look at this
  485.   description before they enter any new realm to see a general overview.
  486.   And by all means, make sure you put a ~ on a line by itself to mark the end
  487.   of the description.  You don't do this, and you'll be asking for trouble.
  488.  
  489.